/**
 * This file is part of 1genia trampoline
 * Copyright (C) 2007 1genia (contact@1genia.com)
 *
 * This library is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; version 3 of the License. 
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details. 
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; see the file COPYING.TXT.  If not,
 * write to the Free Software Foundation, Inc., 51 Franklin Street,
 * Fifth Floor, Boston, MA 02110-1301, USA. 
 **/
package com.genia.toolbox.persistence.jcr.manager;

import com.genia.toolbox.basics.bean.DataContainer;
import com.genia.toolbox.basics.exception.technical.TechnicalException;

/**
 * manager to handle persistence of {@link DataContainer} object.
 */
public interface DataContainerManager
{

  /**
   * delete the information linked to a node identified by its uuid.
   * 
   * @param uuid
   *          the uuid of the persisted {@link DataContainer}
   * @throws TechnicalException
   *           when an error occured
   */
  public void delete(String uuid)
      throws TechnicalException;



  /**
   * returns the {@link DataContainer} associated to an uuid, or
   * <code>null</code> if no such object exists.
   * 
   * @param uuid
   *          the uuid of the {@link DataContainer} to retrieve
   * @return the {@link DataContainer} associated to an uuid, or
   *         <code>null</code> if no such object exists
   * @throws TechnicalException
   *           when an error occured
   */
  public DataContainer getDataContainer(String uuid)
      throws TechnicalException;



  /**
   * returns the {@link DataContainer} representing the file at the given path
   * in the given directory.
   * 
   * @param directoryUuid
   *          the uuid of the directory
   * @param path
   *          the path of the file
   * @return the {@link DataContainer} representing the file at the given path
   *         in the given directory or <code>null</code> if no such directory
   *         of file exists
   * @throws TechnicalException
   *           when an error occured
   */
  public DataContainer getDataContainerFromDirectory(String directoryUuid, String path)
      throws TechnicalException;



  /**
   * returns a random {@link DataContainer} representing a file immediatly under
   * the given path in the given directory. This should be called on a leaf
   * directory if the result must be equitable.
   * 
   * @param directoryUuid
   *          the uuid of the directory
   * @param path
   *          the path of the file
   * @return a random {@link DataContainer} representing a file immediatly under
   *         the given path in the given directory or <code>null</code> if no
   *         data is available
   * @throws TechnicalException
   *           when an error occured
   */
  public DataContainer getRandomDataContainerFromDirectory(String directoryUuid, String path)
      throws TechnicalException;



  /**
   * returns the uuid of a new Node that can be used as a root for a new
   * directory structure.
   * 
   * @return the uuid of a new Node that can be used as a root for a new
   *         directory structure
   * @throws TechnicalException
   *           when an error occured
   */
  public String newDirectory()
      throws TechnicalException;



  /**
   * persist a {@link DataContainer}.
   * 
   * @param dataContainer
   *          the {@link DataContainer} to persist
   * @return the uuid of the persisted {@link DataContainer}
   * @throws TechnicalException
   *           when an error occured
   */
  public String persistDataContainer(DataContainer dataContainer)
      throws TechnicalException;



  /**
   * upload the content of a zip encoded file to the the given directory. If the
   * directory is not null, all its content will be deleted.
   * 
   * @param directoryUuid
   *          the uuid of the directory to upload the content of the file to
   * @param zipDataContainer
   *          the {@link DataContainer} containing the zipped datas
   * @throws TechnicalException
   *           when an error occured
   */
  public void uploadZipDataContainer(String directoryUuid, DataContainer zipDataContainer)
      throws TechnicalException;
}
